home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / spack100.zip / SUPPACK.DOC < prev    next >
Text File  |  1995-01-15  |  24KB  |  547 lines
  1. Suppack version 1.00. Copyright (C) Christian Worm, 1995.
  2.  
  3. =================================================================
  4. 1. Table of contents
  5. =================================================================
  6.  
  7. 1. Table of contents
  8.  
  9. 2. Introduction
  10.    2.1. What is Suppack?
  11.    2.2. Which files constitute the Suppack library?
  12.    2.3. How do I use Suppack?
  13.    2.4. Where can I find the latest version of Suppack?
  14.    2.5. How can I contact the author and how is the support?
  15.  
  16. 3. Formal stuff
  17.    3.1. Copyright & distribution
  18.    3.2. Disclaimer
  19.    3.3. List of all files
  20.  
  21. 4. How to use the C and C++ interfaces
  22.    4.1. Important notes
  23.    4.2. About the interface to standard C
  24.    4.3. About the interface to C++
  25.  
  26. 5. How to use the Pascal interfaces
  27.    5.1. Important notes
  28.    5.2. About the interface to normal Pascal
  29.    5.3. About the interface to OOP-Pascal
  30.  
  31. 6. About the source codes in general
  32.    6.1. Important notes
  33.    6.2. General structure of the source codes
  34.    6.3. It's all bad!
  35.  
  36. 7. Information about the C++ source code
  37.    7.1. Important notes
  38.    7.2. Why use the C++ source code?
  39.    7.3. How to compile the C++ source code
  40.    7.4. What prior work is the suppack derived from?
  41.    7.5. On the tables used by the static huffman part
  42.  
  43. 8. Information about the Assembler source code
  44.    8.1. Important notes
  45.    8.2. How to assemble the library
  46.    8.3. How to assemble to the C/C++ interface
  47.    8.4. How to assemble to the Pascal interface
  48.    8.5. About the structure of the library
  49.    8.6. Organization of data in the work space
  50.    8.7. Some techinfo on the library
  51.  
  52. 9. History
  53.  
  54. 10. Credit
  55.  
  56. =================================================================
  57. 2. Introduction
  58. =================================================================
  59.  
  60. 2.1. What is Suppack?
  61. -----------------------------------------------------------------
  62. Suppack is a library which can be used for general packing and
  63. extraction of data. The user has 100% control over input and
  64. output, hence it should be usable in just about all cases where
  65. packing is required.
  66. As compiled the library requires at least an 80286 processor, but
  67. full source code is included and it is possible to recompile the
  68. library to support 8086/8088. Please note that new versions of
  69. this library might use another format for the packed data than
  70. this one does.
  71.  
  72. 2.2. Which files constitute the Suppack library?
  73. -----------------------------------------------------------------
  74. The files of the Suppack library don't all float around in the
  75. same directory; they are grouped into subdirectories. If you have
  76. received the file SPACK100.ARJ, please remember to unpack it with
  77. the -x switch (arj -x spack100), this tells the archiver to put
  78. the suppack files into the subdirectories where they belong.
  79. When you have installed Suppack in a directory it should contain
  80. the following subdirectories:
  81.  
  82. CINTF    C and C++ interface to the library.
  83. PASINT   Pascal interface, both OOP and ordinary Pascal version.
  84. CPPSOUR  C++ source for the library.
  85. ASMSOUR  Assembler source code for the library.
  86.  
  87. You will only need the files in CPPSOUR and ASMSOUR if you want
  88. to understand how the packer/unpacker works under the hood and/or
  89. want to make changes to the library.
  90. Apart from the abovementioned subdirectories, you should see the
  91. following files:
  92.  
  93. FILE_ID.DIZ  Description of the library.
  94. SUPPACK.DOC  This file.
  95. SUPPACK.EXE  Compiled example of a program which uses the
  96.              library.
  97.  
  98. For a complete list of what the subdirectories contain, see
  99. section 3.3. For a description of the subdirectories in ASMSOUR,
  100. see section 8.5.
  101.  
  102. 2.3. How do I use Suppack?
  103. -----------------------------------------------------------------
  104. Suppack supports the following Intel real mode platforms "out-of-
  105. the-box":
  106.  
  107. 1) C
  108. 2) C++
  109. 3) Turbo Pascal
  110. 4) Turbo Pascal OOP
  111.  
  112. It should also be possible to use the library together with any
  113. other serious programming language but I'm not able to give a
  114. general guide on how to do it.
  115. Interfaces to C(++) and Pascal are put in two different director-
  116. ies, please refer to section 4 and section 5 for details on these
  117. interfaces. It should be noted that all interfaces contain one or
  118. more EXAMPLE*.* files. These are all examples of approximately
  119. the same simple program which can be used as a general file
  120. packer. A compiled version of one of these programmes is included
  121. as the file SUPPACK.EXE. Overall, the library works by calling a
  122. routine for doing the packing or unpacking. In the structured
  123. interfaces this routine must be passed a pointer to a memory area
  124. the library can use and pointers to call-back functions which
  125. must read and write the packed and unpacked data. In the object
  126. oriented languages the interface is an object/a class with
  127. virtual methods for reading and writing data.
  128.  
  129. 2.4. Where can I find the latest version of Suppack?
  130. -----------------------------------------------------------------
  131. The library is available from NightCall BBS aka 2:237/10@fido-
  132. net.org and 2:237/11@fidonet.org. Filerequest SUPPACK for the
  133. latest version.
  134.  
  135. 2.5. How can I contact the author and how is the support?
  136. -----------------------------------------------------------------
  137. As this library is free I cannot guarantee any form of support
  138. for it. I will presumably answer all questions sent as e-mail and
  139. all questions with an enclosed stamped self-addressed envelope
  140. which can be sent from Denmark. But I cannot make any promises.
  141. As to questions and general comments, such as information on bugs
  142. in the packer and bugs in the source code, I can currently be
  143. reached under the name Christian Worm Mortensen at the address
  144. 2:237/10.7@fidonet.org. My snail mail address which all informa-
  145. tion on the actual inclusion of this library in programs are to
  146. be sent to (q.v. section 3.1) is:
  147.  
  148. Christian Worm
  149. Ledavej 80
  150. 9210 Aalborg SO
  151. Denmark
  152.  
  153. =================================================================
  154. 3. Formal stuff
  155. =================================================================
  156.  
  157. 3.1. Copyright & distribution
  158. -----------------------------------------------------------------
  159. The library has been written by Christian Worm who has the full
  160. copyright. With the exception of the C++ source code (see section
  161. 7.4 for details) it can be freely used but under the condition
  162. that information are sent to me as to which programs it is used
  163. in. See section 2.5 for address. The library can be freely
  164. distributed as long it is not modified. See section 3.3 for a
  165. list of all the files the library contains. It is not allowed to
  166. distribute any part of the source code in any modified form
  167. without written permission from the author. If you have made /
  168. consider making changes and feel that others may benefit from
  169. them, please send me a note.
  170.  
  171. 3.2. Disclaimer
  172. -----------------------------------------------------------------
  173. The author makes no warranties, either expressed or implied, with
  174. respect to the material described herein. Should the library
  175. prove defective, the user (and not the author), assumes the
  176. entire cost of all damages. In no event will the author be liable
  177. for direct, indirect, incidental or consequential damages
  178. resulting from any defect in the program.
  179. Other people's work has been used in order to create this
  180. library. Although I certainly do feel I have created this library
  181. myself and that I have the sole right to set the conditions for
  182. use of this library, a judge might think otherwise. Therefore,
  183. the conditions set forth by Yoshizaki that the source to his
  184. program LZHUF (please refer to 7.4 and 8.1) may not be used
  185. commercially may apply to this library, too. If they do, I cannot
  186. take any responsible for that, either.
  187.  
  188. 3.3. List of all files
  189. -----------------------------------------------------------------
  190. The following is a complete of all the files included in the
  191. library and the subdirectories they are placed in.
  192.  
  193. FILE_ID.DIZ
  194. SUPPACK.DOC
  195. SUPPACK.EXE
  196. CINTF\CPPPACK.CPP
  197. CINTF\CPPUNP.CPP
  198. CINTF\EXAMPLE2.CPP
  199. CINTF\EXAMPLE3.CPP
  200. CINTF\EXAMPLE4.C
  201. CINTF\SUPPACK.H
  202. CINTF\SUPPACK.HPP
  203. CINTF\SUPPACK.LIB
  204. PASINTF\EXAMPLE5.PAS
  205. PASINTF\EXAMPLE6.PAS
  206. PASINTF\PASCOMN.OBJ
  207. PASINTF\PASDECOD.OBJ
  208. PASINTF\PASENCOD.OBJ
  209. PASINTF\SUPOPACK.PAS
  210. PASINTF\SUPPACK.PAS
  211. CPPSOUR\EXAMPLE1.CPP
  212. CPPSOUR\HUFFMAN.CPP
  213. CPPSOUR\HUFFMAN.HPP
  214. CPPSOUR\MAKETABL.CPP
  215. CPPSOUR\PACK.CPP
  216. CPPSOUR\PACK.HPP
  217. CPPSOUR\PACKINT.HPP
  218. CPPSOUR\PACKTABL.HPP
  219. CPPSOUR\UNPACK.CPP
  220. CPPSOUR\UNPACK.HPP
  221. CPPSOUR\UNPTABL.HPP
  222. ASMSOUR\PASCOMP.CPP
  223. ASMSOUR\PASCOMP.EXE
  224. ASMSOUR\TASM.CFG
  225. ASMSOUR\BUFFERIO\BUFBITRD.AH
  226. ASMSOUR\BUFFERIO\BUFBITRD.ASM
  227. ASMSOUR\BUFFERIO\BUFBITWR.AH
  228. ASMSOUR\BUFFERIO\BUFBITWR.ASM
  229. ASMSOUR\BUFFERIO\BUFBYTRD.AH
  230. ASMSOUR\BUFFERIO\BUFBYTRD.ASM
  231. ASMSOUR\CTRL\DECODE.AH
  232. ASMSOUR\CTRL\DECODE.ASM
  233. ASMSOUR\CTRL\ENCODE.AH
  234. ASMSOUR\CTRL\ENCODE.ASM
  235. ASMSOUR\CTRL\PACKGEN.AH
  236. ASMSOUR\CTRL\PACKINT.AH
  237. ASMSOUR\CTRL\UNPKINT.AH
  238. ASMSOUR\DHUFFMAN\HUFFGEN.ASM
  239. ASMSOUR\DHUFFMAN\HUFFMAN.AH
  240. ASMSOUR\DHUFFMAN\HUFFPACK.ASM
  241. ASMSOUR\DHUFFMAN\HUFFUNPK.ASM
  242. ASMSOUR\HIGHINTF\HINTFGEN.AH
  243. ASMSOUR\HIGHINTF\HINTFGEN.ASM
  244. ASMSOUR\HIGHINTF\HINTFINT.AH
  245. ASMSOUR\HIGHINTF\HINTFPAC.ASM
  246. ASMSOUR\HIGHINTF\HINTFUNP.ASM
  247. ASMSOUR\LZSS\LZSSGEN.AH
  248. ASMSOUR\LZSS\LZSSPACK.AH
  249. ASMSOUR\LZSS\LZSSPACK.ASM
  250. ASMSOUR\LZSS\LZSSUNPK.AH
  251. ASMSOUR\LZSS\LZSSUNPK.ASM
  252. ASMSOUR\SHUFFMAN\PACKTABL.AH
  253. ASMSOUR\SHUFFMAN\PACKTABL.ASM
  254. ASMSOUR\SHUFFMAN\UNPTABL.AH
  255. ASMSOUR\SHUFFMAN\UNPTABL.ASM
  256.  
  257. =================================================================
  258. 4. How to use the C and C++ interfaces
  259. =================================================================
  260.  
  261. 4.1. Important notes
  262. -----------------------------------------------------------------
  263. Note: You should read section 2.3 before continuing with this
  264. section.
  265. Note: The C and C++ interfaces can be found the subdirectory
  266. named CINTF (q.v. section 2.2).
  267. Note: The code has been written and tested with Borland C++ 4.02
  268. but should work with other compilers.
  269. Note: Unless you are an experienced programmer you will probably
  270. only be able to make the packer work in the large, compact and
  271. maybe huge memory models.
  272.  
  273. 4.2. About the interface to standard C
  274. -----------------------------------------------------------------
  275. In order to use the Suppack library in a C program the file
  276. SUPPACK.LIB must be linked with your program. At the same time
  277. the file SUPPACK.H must be included in the modules which the
  278. packer are to be used in. Four routines are provided - see
  279. SUPPACK.H for an explanation of these and EXAMPLE4.C for an
  280. example of how to use them.
  281.  
  282. 4.3. About the interface to C++
  283. -----------------------------------------------------------------
  284. Note: The C interface can be used directly in a C++ program if
  285. this is desired. One can also use the special C++ interface: It
  286. requires you to link SUPPACK.LIB and one or two of the files
  287. CPPPACK.CPP and CPPUNP.CPP with you program. Depending if you
  288. want to pack, unpack or both. The modules using the interface
  289. should include SUPPACK.HPP - refer to it for closer information
  290. on the usage. EXAMPLE2.CPP and EXAMPLE3.CPP are two different
  291. example programs which do more or less the same thing.
  292. EXAMPL2.CPP uses C++ streams whereas EXAMPLE3.CPP uses Borland/MS
  293. file function calls for file I/O.
  294.  
  295. =================================================================
  296. 5. How to use the Pascal interfaces
  297. =================================================================
  298.  
  299. 5.1. Important notes
  300. -----------------------------------------------------------------
  301. Note: You should read section 2.3 before continuing with this
  302. section.
  303. Note: The Pascal and Pascal OOP interfaces can be found the
  304. subdirectory named PASINTF (q.v. section 2.2).
  305. Note: The code has been written and tested with Turbo Pascal 6.0
  306. but should work with other compilers.
  307.  
  308. 5.2. About the interface to normal Pascal
  309. -----------------------------------------------------------------
  310. In order to use the Suppack library in a non-object oriented
  311. Pascal program one has to use the unit SUPPACK.PAS which handles
  312. all the interfacing to the assembler packing routines. Note that
  313. Turbo Pascal also must be able to find the 3 files PASCOMN.OBJ,
  314. PASDECOD.OBJ, and PASENCOD.OBJ during compilation. See
  315. EXAMPLE5.PAS for an example of how the unit can be used.
  316.  
  317. 5.3. About the interface to OOP-Pascal
  318. -----------------------------------------------------------------
  319. In order to use the Suppack library in an OOP Pascal program one
  320. can use the unit SUPOPACK.PAS which uses the unit SUPPACK.PAS to
  321. interface to the assembler modules (the two units can relatively
  322. easy be combined to one). See EXAMPLE6.PAS for an example of how
  323. the unit can be used.
  324.  
  325. =================================================================
  326. 6. About the source codes in general
  327. =================================================================
  328.  
  329. 6.1. Important notes
  330. -----------------------------------------------------------------
  331. The following sections are about the source code for the library.
  332. It is not necessary to know / use the source code in order to
  333. include the packing routines in one's own programs.
  334. Both C++ and assembler source to the library is included, in the
  335. directories CPPSOUR and ASMSOUR, respectively. See section 7 and
  336. 8 for details.
  337.  
  338. 6.2. General structure of the source codes
  339. -----------------------------------------------------------------
  340. I have put the most general comments on the various source files
  341. in their related header file. A file with the extension AH is an
  342. assembly header, one with the extension HPP is a C++ header, and
  343. one with the extension H is a C header. A header file which name
  344. ends in INT is an "internal" header file - i.e. one which is used
  345. by a limited number of modules. A file with the ending GEN is a
  346. general header file - i.e. one which is used by many different
  347. modules and doesn't have a specific source file connected to it.
  348. There is no clear distinction between these two types.
  349.  
  350. 6.3. It's all bad!
  351. -----------------------------------------------------------------
  352. There are surely loads of errors in the comments, especially for
  353. the assembler code - I haven't checked them.
  354. I am fully aware that the code is not commented perfectly and I
  355. considered not releasing the source. So if you want to nag please
  356. have in mind that the alternative to this mess would have been
  357. that no source code were released. Remember that I have not
  358. earned a single penny on this packer! Nevertheless, I would like
  359. to hear concrete suggestions for changes to the comments.
  360.  
  361. =================================================================
  362. 7. Information about the C++ source code
  363. =================================================================
  364.  
  365. 7.1. Important notes
  366. -----------------------------------------------------------------
  367. Note: You should read section 6 before continuing with this
  368. section.
  369. Note: The C++ source code can be found the subdirectory named
  370. CPPSOUR (q.v. section 2.2).
  371. Note: PACKINT.HPP contains a general description of the packers
  372. working method.
  373.  
  374. 7.2. Why use the C++ source code?
  375. -----------------------------------------------------------------
  376. The C++ version of the library has the "benefit" of being more
  377. cumbersome to use than the assembler version, take up more space,
  378. be _a_lot_ slower, and it has a limitation which makes it unable
  379. to handle error reports from the user's own I/O routines. The
  380. reason for it being included despite all this is that if one
  381. tries to look under the hood of the packer it is a lot easier to
  382. understand than the assembler version which isn't as richly
  383. commented. This code is only meant to be an aid in understanding
  384. the workings of the packer and the assembler source code. 
  385.  
  386. 7.3. How to compile the C++ source code
  387. -----------------------------------------------------------------
  388. The classes which makes up the interface to the user are not 100%
  389. compatible with those which are in the C++ interface to the
  390. assembler packer - see EXAMPLE1.CPP for information on how they
  391. work. To test the source code all the compiled .CPP files except
  392. for the file MAKETABL.CPP are to be linked together.
  393. Please note that the source code has been written for and tested
  394. with Borland C++ 4.02. I cannot guarantee that it will work with
  395. other compilers and I would like to hear about problems (not
  396. including problems with BC++ 3.0 which is so bugridden that I
  397. don't have any ambitions of making the packer work under it).
  398.  
  399. 7.4. What prior work is the suppack derived from?
  400. -----------------------------------------------------------------
  401. In case anyone wants more information I can inform that the
  402. source code has been built around LZHUF which is written by
  403. Haruyasu Yoshizaki. LZHUF is released together with two other
  404. packers, namely LZSS, LZARI together with an article describing
  405. how the packers work in general.
  406. Please note that some parts of the C++ packer has been copied
  407. verbatim from LZHUF and that it is not allowed to use LZHUF for
  408. commercial purposes. Hence, it is not allowed to use the C++
  409. packer for commercial purposes - which, to be honest, probably
  410. would be a hindrance.
  411.  
  412. 7.5. On the tables used by the static huffman part
  413. -----------------------------------------------------------------
  414. The program MAKETABL.CPP is used to create the table used by the
  415. static huffman compression used in both the packer as well as the
  416. unpacker. These tables are put in the two header files
  417. PACKTABL.HPP and UNPTABL.HPP. The tables are also used by the
  418. assembler library and you have to convert them to assembler
  419. source code by hand if you make changes.
  420.  
  421. =================================================================
  422. 8. Information about the Assembler source code
  423. =================================================================
  424.  
  425. 8.1. Important notes
  426. -----------------------------------------------------------------
  427. Note: You should read section 6 before continuing with this
  428. section.
  429. Note: The directory ASMSOUR contains assembler routines which are
  430. translated from the routines in the CPPSOUR directory (see
  431. section 7). Even though they resemble each other in structure,
  432. this is not a case of line by line translation. There are certain
  433. differences.
  434. Note: You should refer to CTRL\PACKGEN.AH for information on how
  435. the library can be reassembled to support 8086/8088.
  436.  
  437. 8.2. How to assemble the library
  438. -----------------------------------------------------------------
  439. The source is written for TASM MASM mode, I cannot guarantee that
  440. it will work if assembled with MASM and would like to hear about
  441. any trouble.
  442. The library should be assembled in different ways depending on
  443. whether it is to be used with C/C++ or Pascal. Note that the
  444. C/C++ interface in principle also can use the assembled Pascal
  445. library.
  446.  
  447. 8.3. How to assemble to the C/C++ interface
  448. -----------------------------------------------------------------
  449. The library can be created by assembling all .ASM files and
  450. putting the OBJ files into the SUPPACK.LIB library which is used
  451. by the C/C++ interface.
  452.  
  453. 8.4. How to assemble to the Pascal interface
  454. -----------------------------------------------------------------
  455. The program PASCOMP.EXE with source code in PASCOMP.CPP (sorry
  456. that the source is not in Pascal - that language is not where I
  457. show my excellence), merges all the assembler files into three
  458. new assembler files which must be assembled to OBJ format. It is
  459. these three files that the Pascal interface uses. It is split
  460. into three files to ensure that a program which uses only the
  461. packer or uses only the unpacker doesn't link in any extraneous
  462. code.
  463.  
  464. 8.5. About the structure of the library
  465. -----------------------------------------------------------------
  466. Note: You should refer to the C++ source code for information on
  467. how the packing/unpacking works. The various directories stored
  468. in the ASMSOUR subdirectory are:
  469.  
  470. LZSS     This directory contains routines for LZSS packing and
  471.          unpacking. However, the LZSS packing is partially done
  472.          by ENCODE.ASM elsewhere.
  473. DHUFFMAN This directory contains all routines to be used with
  474.          dynamic huffman packing and unpacking.
  475. SHUFFMAN This directory contains tables used with static huffman.
  476.          The tables are made by MAKETABL.CPP in the C++ source
  477.          code (q.v. section 7.5).
  478. BUFFERIO This is the place for the following modules all working
  479.          with buffers:
  480.          1) A module which can read bit by bit and which gets its
  481.          data from the function user_read (see below).
  482.          2) A module which can write bit by bit and which writes
  483.          itself by calling user_write (see below)
  484.          3) A module which can read byte by byte and which gets
  485.          data from user_read.
  486.          There is no module for writing byte by byte since this
  487.          is included in the LZSS unpacker part.
  488. CTRL     Here is the packing/unpacking routines which controls
  489.          the other modules. This directory also contains some
  490.          header files which configure the packer and its memory
  491.          usage and which is included by all files (see below).
  492. HIGHINTF The modules in this directory create the interface to
  493.          high level languages. This is done by, amongst other
  494.          things, supporting parameters passed on the stack and by
  495.          setting up ES and DS to point at the data areas which
  496.          the packer uses and by clearing the direction flag. It
  497.          is also done by declaring user_read and user_write and
  498.          passing calls to these on to the user.
  499.  
  500. 8.6. Organization of data in the work space
  501. -----------------------------------------------------------------
  502. The routines should be given some work space by the user and the
  503. space is organized in the following way: The various modules
  504. declare a struc with the name *_mem containing the data they
  505. need. CTRL\PACKGEN.AH defines macros for defining these data in
  506. this segment. These definitions are performed in the following
  507. files:
  508.  
  509. CTRL\PACKGEN.AH: Declares strucs common to packer and unpacker
  510. CTRL\UNPKINT.AH: Declares strucs particular to unpacker
  511. CTRL\PACKINT.AH: Declares strucs particular to packer
  512.  
  513. 8.7. Some techinfo on the library
  514. -----------------------------------------------------------------
  515. The registers BP, SI, DI, DS, and ES are saved at every call to
  516. the packer but only DS will be preserved for the call-back
  517. routines. The routines reset the direction flag and always
  518. deliver it reset. All code is put in the segment PACK_TEXT. The
  519. routines should be 100% reentrant although I haven't tested it.
  520.  
  521. =================================================================
  522. 9. History
  523. =================================================================
  524. Version  News
  525. 0.90a    First version, with restrictions on distribution.
  526. 1.0      1) EXAMPLE files and documentaion translated into
  527.          english.
  528.          2) The different DOC files joined to one.
  529.          3) Minor changes to the highlevel language interfaces.
  530.  
  531. =================================================================
  532. 10. Credit
  533. =================================================================
  534. Thanks to SUne Trudslev (2:236/174.17@fidonet.org) for making a
  535. translation of all manuals into English.
  536. Thanks to Peter Finderup Lund (2:234/99.16@fidonet.org and
  537. firefly@hib.ruc.dk), also for making a translation of all manuals
  538. into English.
  539. The main parts of the manuals are based on PFL's edition. The
  540. places where there are grammar errors are probably the places
  541. where I have written something myself :-)
  542.  
  543. Thanks to SUne Trudslev for translating all the non-documentation
  544. material into English.
  545.  
  546. Thanks to Peter Finderup Lund for writing a draft for the Pascal
  547. interface.